Python DRF Serializer Relations: 중첩 객체 직렬화 마스터하기

Django REST Framework (DRF)는 웹 API 구축을 위한 강력하고 유연한 시스템을 제공합니다. API 개발의 중요한 측면은 데이터 모델 간의 관계를 처리하는 것이며, DRF serializer는 중첩된 객체를 직렬화하고 역직렬화하는 강력한 메커니즘을 제공합니다. 이 가이드에서는 DRF serializer에서 관계를 관리하는 다양한 방법을 살펴보고 실용적인 예제와 모범 사례를 제공합니다.

Serializer 관계 이해

관계형 데이터베이스에서 관계는 서로 다른 테이블 또는 모델이 연결되는 방식을 정의합니다. DRF serializer는 API 소비를 위해 데이터베이스 객체를 JSON 또는 다른 데이터 형식으로 변환할 때 이러한 관계를 반영해야 합니다. 세 가지 주요 관계 유형을 다룹니다.

• ForeignKey (일대다): 단일 객체가 여러 다른 객체와 관련됩니다. 예를 들어, 한 작가가 여러 권의 책을 쓸 수 있습니다.
• ManyToManyField (다대다): 여러 객체가 여러 다른 객체와 관련됩니다. 예를 들어, 여러 작가가 여러 권의 책을 공동 작업할 수 있습니다.
• OneToOneField (일대일): 하나의 객체가 다른 객체와 고유하게 관련됩니다. 예를 들어, 사용자 프로필은 종종 사용자 계정과 일대일로 연결됩니다.

ForeignKey를 사용한 기본 중첩 직렬화

ForeignKey 관계를 직렬화하는 간단한 예제부터 시작하겠습니다. 다음 모델을 고려하십시오.

from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)
    country = models.CharField(max_length=50, default='USA') # 국제적 맥락을 위해 국가 필드 추가

    def __str__(self):
        return self.name

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books')
    publication_date = models.DateField()

    def __str__(self):
        return self.title

관련된 `Author` 데이터와 함께 `Book` 모델을 직렬화하려면 중첩된 serializer를 사용할 수 있습니다.

from rest_framework import serializers

class AuthorSerializer(serializers.ModelSerializer):
    class Meta:
        model = Author
        fields = ['id', 'name', 'country']

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer(read_only=True) # PrimaryKeyRelatedField에서 변경됨

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

이 예제에서 `BookSerializer`에는 `AuthorSerializer` 필드가 포함되어 있습니다. `read_only=True`는 `author` 필드를 읽기 전용으로 만들어 책 엔드포인트를 통해 작성자를 수정하는 것을 방지합니다. 작성자 정보가 있는 책을 만들거나 업데이트해야 하는 경우 쓰기 작업을 다르게 처리해야 합니다 (아래 참조).

이제 `Book` 객체를 직렬화하면 JSON 출력에 책 데이터 내에 중첩된 전체 작성자 세부 정보가 포함됩니다.

{
    "id": 1,
    "title": "The Hitchhiker's Guide to the Galaxy",
    "author": {
        "id": 1,
        "name": "Douglas Adams",
        "country": "UK"
    },
    "publication_date": "1979-10-12"
}

ManyToManyField 관계 직렬화

`ManyToManyField` 관계를 고려해 보겠습니다. `Category` 모델이 있고 책이 여러 범주에 속할 수 있다고 가정합니다.

class Category(models.Model):
    name = models.CharField(max_length=100)

    def __str__(self):
        return self.name

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books')
    categories = models.ManyToManyField(Category, related_name='books')
    publication_date = models.DateField()

    def __str__(self):
        return self.title

`serializers.StringRelatedField` 또는 `serializers.PrimaryKeyRelatedField`를 사용하여 범주를 직렬화하거나 중첩된 serializer를 만들 수 있습니다.

class CategorySerializer(serializers.ModelSerializer):
    class Meta:
        model = Category
        fields = ['id', 'name']

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer(read_only=True)
    categories = CategorySerializer(many=True, read_only=True) # ManyToManyField에 many=True가 필수적입니다.

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'categories', 'publication_date']

`many=True` 인수는 `ManyToManyField`를 직렬화할 때 매우 중요합니다. 이는 serializer에게 범주 객체 목록을 예상하도록 지시합니다. 출력은 다음과 같습니다.

{
    "id": 1,
    "title": "Pride and Prejudice",
    "author": {
        "id": 2,
        "name": "Jane Austen",
        "country": "UK"
    },
    "categories": [
        {
            "id": 1,
            "name": "Classic Literature"
        },
        {
            "id": 2,
            "name": "Romance"
        }
    ],
    "publication_date": "1813-01-28"
}

OneToOneField 관계 직렬화

`OneToOneField` 관계의 경우 접근 방식은 ForeignKey와 유사하지만 관련 객체가 존재하지 않을 수 있는 경우를 처리하는 것이 중요합니다.

from django.contrib.auth.models import User

class UserProfile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE, related_name='profile')
    bio = models.TextField(blank=True)
    location = models.CharField(max_length=100, blank=True, default='Global') # 국제적 맥락을 위해 위치 추가

    def __str__(self):
        return self.user.username

class UserProfileSerializer(serializers.ModelSerializer):
    class Meta:
        model = UserProfile
        fields = ['id', 'bio', 'location']

class UserSerializer(serializers.ModelSerializer):
    profile = UserProfileSerializer(read_only=True)

    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'profile']

출력은 다음과 같습니다.

{
    "id": 1,
    "username": "johndoe",
    "email": "john.doe@example.com",
    "profile": {
        "id": 1,
        "bio": "Software Engineer.",
        "location": "London, UK"
    }
}

쓰기 작업 처리 (생성 및 업데이트)

위의 예제는 주로 읽기 전용 직렬화에 중점을 둡니다. 관련 객체를 만들거나 업데이트할 수 있도록 하려면 serializer에서 `create()` 및 `update()` 메서드를 재정의해야 합니다.

중첩된 객체 생성

새 책과 작성자를 동시에 만들고 싶다고 가정해 보겠습니다.

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer()

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

    def create(self, validated_data):
        author_data = validated_data.pop('author')
        author = Author.objects.create(**author_data)
        book = Book.objects.create(author=author, **validated_data)
        return book

`create()` 메서드에서 작성자 데이터를 추출하고 새 `Author` 객체를 만든 다음 새로 만든 작성자와 연결하여 `Book` 객체를 만듭니다.

중요: `author_data`에서 잠재적인 유효성 검사 오류를 처리해야 합니다. try-except 블록을 사용하고 작성자 데이터가 유효하지 않은 경우 `serializers.ValidationError`를 발생시킬 수 있습니다.

중첩된 객체 업데이트

마찬가지로 책과 작성자를 모두 업데이트하려면 다음을 수행합니다.

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer()

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

    def update(self, instance, validated_data):
        author_data = validated_data.pop('author', None)

        if author_data:
            author = instance.author
            for attr, value in author_data.items():
                setattr(author, attr, value)
            author.save()

        for attr, value in validated_data.items():
            setattr(instance, attr, value)
        instance.save()

        return instance

`update()` 메서드에서 기존 작성자를 검색하고 제공된 데이터를 기반으로 해당 속성을 업데이트한 다음 책의 속성을 업데이트합니다. `author_data`가 제공되지 않은 경우 (작성자가 업데이트되지 않음을 의미) 코드는 작성자 업데이트 섹션을 건너뜁니다. `validated_data.pop('author', None)`의 `None` 기본값은 업데이트 요청에 작성자 데이터가 포함되지 않은 경우를 처리하는 데 매우 중요합니다.

`PrimaryKeyRelatedField` 사용

중첩된 serializer 대신 `PrimaryKeyRelatedField`를 사용하여 관련 객체의 기본 키를 사용하여 관계를 나타낼 수 있습니다. 관련 객체의 ID만 참조해야 하고 전체 객체를 직렬화하지 않으려는 경우에 유용합니다.

class BookSerializer(serializers.ModelSerializer):
    author = serializers.PrimaryKeyRelatedField(queryset=Author.objects.all())

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

이제 `author` 필드에 작성자의 ID가 포함됩니다.

{
    "id": 1,
    "title": "1984",
    "author": 3,  // 작성자 ID
    "publication_date": "1949-06-08"
}

생성 및 업데이트의 경우 요청 데이터에 작성자의 ID를 전달합니다. `queryset=Author.objects.all()`은 제공된 ID가 데이터베이스에 있는지 확인합니다.

`HyperlinkedRelatedField` 사용

`HyperlinkedRelatedField`는 관련 객체의 API 엔드포인트에 대한 하이퍼링크를 사용하여 관계를 나타냅니다. 이는 하이퍼미디어 API (HATEOAS)에서 일반적입니다.

class BookSerializer(serializers.ModelSerializer):
    author = serializers.HyperlinkedRelatedField(view_name='author-detail', read_only=True)

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

`view_name` 인수는 관련 객체에 대한 요청을 처리하는 뷰의 이름 (예: `author-detail`)을 지정합니다. `urls.py`에서 이 뷰를 정의해야 합니다.

출력에는 작성자의 세부 정보 엔드포인트를 가리키는 URL이 포함됩니다.

{
    "id": 1,
    "title": "Brave New World",
    "author": "http://example.com/api/authors/4/",
    "publication_date": "1932-01-01"
}

고급 기술 및 고려 사항

• `depth` 옵션: `ModelSerializer`에서 `depth` 옵션을 사용하여 특정 깊이까지 ForeignKey 관계에 대한 중첩된 serializer를 자동으로 만들 수 있습니다. 그러나 `depth`를 사용하면 관계가 복잡한 경우 성능 문제가 발생할 수 있으므로 serializer를 명시적으로 정의하는 것이 좋습니다.
• `SerializerMethodField`: `SerializerMethodField`를 사용하여 관련 데이터에 대한 사용자 지정 직렬화 논리를 만듭니다. 특정 방식으로 데이터를 포맷하거나 계산된 값을 포함해야 하는 경우에 유용합니다. 예를 들어, 로케일을 기준으로 작성자의 전체 이름을 다른 순서로 표시할 수 있습니다. 많은 아시아 문화권에서는 성이 이름보다 먼저 나옵니다.
• 표현 사용자 지정: serializer에서 `to_representation()` 메서드를 재정의하여 관련 데이터가 표현되는 방식을 사용자 지정합니다.
• 성능 최적화: 복잡한 관계와 대규모 데이터 세트의 경우 select_related 및 prefetch_related와 같은 기술을 사용하여 데이터베이스 쿼리를 최적화하고 데이터베이스 히트 수를 줄입니다. 이는 연결 속도가 느릴 수 있는 글로벌 사용자를 대상으로 하는 API에 특히 중요합니다.
• Null 값 처리: 특히 선택적 관계를 처리할 때 serializer에서 null 값이 처리되는 방식에 유의하십시오. 필요한 경우 serializer 필드에서 `allow_null=True`를 사용하십시오.
• 유효성 검사: 특히 관련 객체를 만들거나 업데이트할 때 데이터 무결성을 보장하기 위해 강력한 유효성 검사를 구현합니다. 사용자 지정 유효성 검사기를 사용하여 비즈니스 규칙을 적용하는 것을 고려하십시오. 예를 들어, 책의 발행일은 미래가 아니어야 합니다.
• 국제화 및 지역화 (i18n/l10n): 데이터가 다른 언어와 지역에서 어떻게 표시되는지 고려하십시오. 사용자 로케일에 맞게 날짜, 숫자 및 통화를 적절하게 포맷하십시오. 모델 및 serializer에 국제화 가능한 문자열을 저장하십시오.

Serializer 관계에 대한 모범 사례

• Serializer를 집중적으로 유지: 각 serializer는 특정 모델 또는 밀접하게 관련된 데이터 집합을 직렬화하는 역할을 해야 합니다. 지나치게 복잡한 serializer를 만들지 마십시오.
• 명시적 Serializer 사용: `depth` 옵션에 너무 많이 의존하지 마십시오. 직렬화 프로세스를 더 잘 제어하기 위해 각 관련 모델에 대해 명시적 serializer를 정의하십시오.
• 철저하게 테스트: serializer가 데이터를 올바르게 직렬화 및 역직렬화하는지 확인하기 위해 단위 테스트를 작성하십시오. 특히 복잡한 관계를 처리할 때 그렇습니다.
• API 문서화: API 엔드포인트와 예상하고 반환하는 데이터 형식을 명확하게 문서화하십시오. Swagger 또는 OpenAPI와 같은 도구를 사용하여 대화형 API 문서를 생성하십시오.
• API 버전 관리 고려: API가 발전함에 따라 기존 클라이언트와의 호환성을 유지하기 위해 버전 관리를 사용하십시오. 이를 통해 이전 응용 프로그램에 영향을 주지 않고 주요 변경 사항을 도입할 수 있습니다.
• 성능 모니터링: API의 성능을 모니터링하고 serializer 관계와 관련된 병목 현상을 식별하십시오. 프로파일링 도구를 사용하여 데이터베이스 쿼리 및 직렬화 논리를 최적화하십시오.

결론

Django REST Framework에서 serializer 관계를 마스터하는 것은 강력하고 효율적인 웹 API를 구축하는 데 필수적입니다. 다양한 유형의 관계와 DRF serializer에서 사용할 수 있는 다양한 옵션을 이해함으로써 중첩된 객체를 효과적으로 직렬화하고 역직렬화하고, 쓰기 작업을 처리하고, 성능을 위해 API를 최적화할 수 있습니다. API가 전 세계 사용자에게 액세스할 수 있도록 API를 설계할 때 국제화 및 지역화를 고려하십시오. 철저한 테스트와 명확한 문서는 API의 장기적인 유지 관리 가능성과 유용성을 보장하는 데 핵심입니다.